<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>Programming in Lua : 15.1</title>
<link rel="stylesheet" type="text/css" href="pil.css">
</head>
<body>
<p class="warning">
<A HREF="contents.html"><IMG TITLE="Programming in Lua (first edition)" SRC="capa.jpg" ALT="" ALIGN="left"></A>This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.<BR>The third edition targets Lua 5.2 and is available at <A HREF="http://www.amazon.com/exec/obidos/ASIN/859037985X/theprogrammil3-20">Amazon</A> and other bookstores.<BR>By buying the book, you also help to <A HREF="../donations.html">support the Lua project</A>.
</p>
<table width="100%" class="nav">
<tr>
<td width="10%" align="left"><a href="15.html"><img border="0" src="left.png" alt="Previous"></a></td>
<td width="80%" align="center"><a href="contents.html"><font face="Helvetica,Arial,sanserif">
<font color="gray">Programming in </font><font color="blue"> Lua</font>
</font></a></td>
<td width="10%" align="right"><a href="15.2.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
<tr>
<td width="10%" align="left"></td>
<td width="80%" align="center"><a href="contents.html#P2">Part II. Tables and Objects</a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="contents.html#15">Chapter 15. Packages</a></td>
<td width="10%" align="right"></td></tr>
</table>
<hr/>
<p><h2>15.1 &ndash; The Basic Approach</h2>

<p>A simple way to define a package is to write
the package name as a prefix for each object in the package.
For instance, suppose we are writing a library to manipulate
complex numbers.
We represent each complex number as a table,
with fields <code>r</code> (real part) and <code>i</code> (imaginary part).
We declare all our new operations in another table,
which acts as a new package:
<pre>
    complex = {}
    
    function complex.new (r, i) return {r=r, i=i} end
    
    -- defines a constant `i'
    complex.i = complex.new(0, 1)
    
    function complex.add (c1, c2)
      return complex.new(c1.r + c2.r, c1.i + c2.i)
    end
    
    function complex.sub (c1, c2)
      return complex.new(c1.r - c2.r, c1.i - c2.i)
    end
    
    function complex.mul (c1, c2)
      return complex.new(c1.r*c2.r - c1.i*c2.i,
                         c1.r*c2.i + c1.i*c2.r)
    end
    
    function complex.inv (c)
      local n = c.r^2 + c.i^2
      return complex.new(c.r/n, -c.i/n)
    end
    
    return complex
</pre>
This library defines one single global name, <code>complex</code>.
All other definitions go inside this table.

<p>With this definition,
we can use any complex operation qualifying the operation name,
like this:
<pre>
    c = complex.add(complex.i, complex.new(10, 20))
</pre>

<p>This use of tables for packages does not provide exactly the same
functionality as provided by real packages.
First, we must explicitly put the package name in every function
definition.
Second, a function that calls another function
inside the same package must qualify the name of the called function.
We can ameliorate those problems using a fixed local name
for the package (<code>P</code>, for instance),
and then assigning this local to the final name of the package.
Following this guideline, we would write our previous definition like
this:
<pre>
    local P = {}
    complex = P           -- package name
    
    P.i = {r=0, i=1}
    function P.new (r, i) return {r=r, i=i} end
    
    function P.add (c1, c2)
      return P.new(c1.r + c2.r, c1.i + c2.i)
    end
    
       ...
</pre>
Whenever a function calls another function inside the same package
(or whenever it calls itself recursively),
it still needs to prefix the name.
At least, the connection between the two functions
does not depend on the package name anymore.
Moreover, there is only one place in the whole package
where we write the package name.

<p>Maybe you noticed that the last statement in the package was
<pre>
    return complex
</pre>
This return is not necessary,
because the package is already assigned to a global variable
(<code>complex</code>).
Nevertheless, we consider a good practice that a package
returns itself when it opens.
The extra return costs nothing,
and allows alternative ways to handle the package.

<hr/>
<table width="100%" class="nav">
<tr valign="top">
<td width="90%" align="left">
<small>
  Copyright &copy; 2003&ndash;2004 Roberto Ierusalimschy.  All rights reserved.
</small>
</td>
<td width="10%" align="right"><a href="15.2.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
</table>


</body></html>

